Repository navigation
Conversation
|
First try integrating the docs from the c5c3/cobaltcore repository AS-IS as a first step. |
|
@berendt, why not migrating your workflows to this repo and setting up an infra for that? Are there any engineering or organizational blockers? |
I'm not quite sure yet how that's supposed to work. In my opinion, documentation belongs with the individual projects and shouldn't be managed in a central Docs repository. For example, we have E2E tests for every guide we have. How is that supposed to work properly if the guide is in a different repository than our E2E tests? I think it's a good idea to publish the documentation in a curated, centralized location. In my opinion, the documentation should be maintained in the respective repositories. Otherwise, it will quickly become disjointed. Even if we later publish security advisories or release interim versions for individual projects along with release notes, I believe that this information belongs within the respective projects and should only be published centrally afterward. |
The OpenStack section was a set of hand-written pages that described a Helm chart that does not exist and covered five of the nine services. C5C3/cobaltcore documents the OpenStack layer completely and declares in docs/.vitepress/publish.json which of its pages cobaltcore.dev may publish (C5C3/cobaltcore#1647). hack/sync-cobaltcore.sh puts a sparse checkout of C5C3/cobaltcore (docs, tests, deploy) into docs/_upstream/cobaltcore. npm runs it before docs:dev and docs:build; it leaves an existing checkout alone and copies a local checkout when COBALTCORE_SRC names one. The directory is ignored by git and docker. docs/.vitepress/overlay.ts mounts the published pages under /openstack/ without copying a file: rewrites maps the checkout, srcExclude drops every other Markdown file of it, and a markdown-it rule resolves each link against the page's real source file. A link to a published page stays on this site, a link to an unpublished page goes to c5c3.github.io/cobaltcore, and a link to a file outside docs/ goes to GitHub. The /openstack/ sidebar is the upstream sidebar pruned to the published pages, and "Edit this page" opens the file in C5C3/cobaltcore. The overview pages of the nine service operators keep the URLs of the old pages, /openstack/nova and so on, so the old pages go. Built against C5C3/cobaltcore@840f88fd8 with Node 22.23: 123 pages, 81 of them under /openstack/, no dead link; the 371 internal links of those pages resolve and their 83 distinct links to c5c3.github.io answer 200. Part of C5C3/cobaltcore#1646. On-behalf-of: @SAP Assisted-by: Claude:claude-opus-5-5 Signed-off-by: Christian Berendt <berendt@23technologies.cloud>
The build job checks out C5C3/cobaltcore main into docs/_upstream/cobaltcore before npm ci, sparsely (docs, tests, deploy) and without persisting the token, so the sync hook of docs:build finds the checkout and leaves it alone. A nightly schedule rebuilds and deploys the site, so a change to the C5C3/cobaltcore docs reaches the OpenStack section within a day; the deploy job already runs on every event but a pull request. actionlint reports nothing for the workflow. Part of C5C3/cobaltcore#1646. On-behalf-of: @SAP Assisted-by: Claude:claude-opus-5-5 Signed-off-by: Christian Berendt <berendt@23technologies.cloud>
The overlay loads docs/.vitepress/sidebar.ts of C5C3/cobaltcore with import(), which needs the type stripping Node 22.18 and later has built in; the README said Node 18. CI and the image already run Node 26. The image runs docs:dev, whose predocs:dev hook runs hack/sync-cobaltcore.sh. node:26-alpine has neither bash nor git, so the image installs both and copies the script. With docs/_upstream absent, `docker compose run vitepress npm run docs:build` cloned C5C3/cobaltcore into the mounted directory and built 81 pages under /openstack/. The README describes the OpenStack section, the sync step and the preview of a local C5C3/cobaltcore checkout with COBALTCORE_SRC. Part of C5C3/cobaltcore#1646. On-behalf-of: @SAP Assisted-by: Claude:claude-opus-5-5 Signed-off-by: Christian Berendt <berendt@23technologies.cloud>
Five pages described OpenStack the way the removed pages did. Step 5 of the minimal environment installed a Helm chart cobaltcore/openstack that does not exist; it now explains the ControlPlane resource and points to Quick Start (ControlPlane) and Quick Start (metal-stack). The platform bootstrap order said "via Helm" and now names the operators and the ControlPlane resource. The diagrams of the architecture overview and the full deployment list the nine services the OpenStack section covers, and the OpenStack checklist of the full deployment links Quick Start (ControlPlane) and adds Placement, Barbican and Horizon. Getting Started gains an OpenStack control plane track, and docs/networking/ovn.md links the OVN operator at /openstack/ovn. Part of C5C3/cobaltcore#1646. On-behalf-of: @SAP Assisted-by: Claude:claude-opus-5-5 Signed-off-by: Christian Berendt <berendt@23technologies.cloud>
93b324b to
9e36ca4
Compare
We need to talk and find a meaningful solution. I'll also need to onboard you to the latest state. |
|
As agreed, let's follow with the repo in the Org and move the code & docs there. |
Closes #89. The cobaltcore-dev/docs side of C5C3/cobaltcore#1646; the C5C3/cobaltcore side shipped in C5C3/cobaltcore#1647.
The OpenStack section is now the documentation of C5C3/cobaltcore, checked out at build time and mounted under
/openstack/. No file of C5C3/cobaltcore is committed here. The hand-written OpenStack pages, which described a Helm chart that does not exist and covered five of nine services, are gone; the overlay serves their URLs.Commits
hack/sync-cobaltcore.shputs a sparse checkout (docs, tests, deploy) intodocs/_upstream/cobaltcore, ignored by git and docker. npm runs it beforedocs:devanddocs:build; it leaves an existing checkout alone, and withCOBALTCORE_SRCit copies a local checkout.docs/.vitepress/overlay.ts(the prototype from Build the OpenStack section from the C5C3/cobaltcore docs as a build-time overlay #89) mounts the pages thatpublish.jsonlists:rewritesmaps them,srcExcludedrops every other Markdown file of the checkout, and a markdown-it rule resolves links against the real source file. Links to published pages stay here, links to unpublished pages go to c5c3.github.io/cobaltcore, and links to files outsidedocs/go to GitHub. The/openstack/sidebar is the upstream sidebar pruned to published pages, and "Edit this page" opens the file in C5C3/cobaltcore.static.ymlchecks out C5C3/cobaltcoremainsparsely beforenpm ci(no persisted token), and a nightly schedule rebuilds and deploys the site.sidebar.tsneeds Node's built-in type stripping. The image needs bash and git for the sync hook. The README describes the OpenStack section and the local preview.docs/networking/ovn.mdlinks/openstack/ovn.The optional table CSS from #89 is left out: VitePress' default theme already gives
.vp-doc tabledisplay: blockandoverflow-x: auto.Verification
Against C5C3/cobaltcore@840f88fd8:
npm run docs:sync && npm run docs:buildwith Node 22.23 and 24.21: 81 pages under/openstack/, no dead link, nothing else of the checkout rendered. Rebased ontomainand built with Node 25.1: 124 pages, 81 of them under/openstack/; the 43 pages outside/openstack/are the same as onmain, and the six old OpenStack URLs are served by the overlay.C5C3/cobaltcore/edit/main/docs/…. The sidebar groups are Quick Starts, Architecture, Guides, Services, Reference.vitepress preview:/openstack/, a guide,/openstack/novaand/openstack/quick-start-controlplaneanswer 200. Invitepress dev, the page module of a guide carries the rewritten links.hack/sync-cobaltcore.sh: clones when the checkout is missing, leaves it alone on the next run, copies withCOBALTCORE_SRC, and stops with a message on an incomplete directory or a wrongCOBALTCORE_SRC. shellcheck reports nothing.docker compose build, thendocker compose run vitepress npm run docs:buildwith the checkout missing: the hook clones in the container, and the build produces 81 OpenStack pages.docs-overlayjob of C5C3/cobaltcore, emulated against this branch: its check findsdocs/.vitepress/overlay.ts, andnpm ci && npm run docs:buildwith the job's checkout passes and leaves the checkout alone.actionlintreports nothing forstatic.yml.After the merge, the nightly build and the
docs-overlayjob of C5C3/cobaltcore run againstmainhere; C5C3/cobaltcore#1646 can be closed once cobaltcore.dev shows the section.🤖 Generated with Claude Code